Breaking changes

• ERC1967Utils: Removed duplicate declaration of the Upgraded, AdminChanged and BeaconUpgraded events. These events are still available through the IERC1967 interface located under the contracts/interfaces/ directory. Minimum pragma version is now 0.8.21.
• Governor, GovernorCountingSimple: The _countVote virtual function now returns an uint256 with the total votes casted. This change allows for more flexibility for partial and fractional voting. Upgrading users may get a compilation error that can be fixed by adding a return statement to the _countVote function.

Custom error changes

This version comes with changes to the custom error identifiers. Contracts previously depending on the following errors should be replaced accordingly:

• Replace Address.FailedInnerCall with Errors.FailedCall
• Replace Address.AddressInsufficientBalance with Errors.InsufficientBalance
• Replace Clones.Create2InsufficientBalance with Errors.InsufficientBalance
• Replace Clones.ERC1167FailedCreateClone with Errors.FailedDeployment
• Replace Clones.Create2FailedDeployment with Errors.FailedDeployment
• SafeERC20: Replace Address.AddressEmptyCode with SafeERC20FailedOperation if there is no code at the token's address.
• SafeERC20: Replace generic Error(string) with SafeERC20FailedOperation if the returned data can't be decoded as bool.
• SafeERC20: Replace generic SafeERC20FailedOperation with the revert message from the contract call if it fails.

Changes by category

General

• AccessManager, VestingWallet, TimelockController and ERC2771Forwarder: Added a public initializer function in their corresponding upgradeable variants. (#5008)

Access

• AccessControlEnumerable: Add a getRoleMembers method to return all accounts that have role. (#4546)
• AccessManager: Allow the onlyAuthorized modifier to restrict functions added to the manager. (#5014)

Finance

• VestingWalletCliff: Add an extension of the VestingWallet contract with an added cliff. (#4870)

Governance

• GovernorCountingFractional: Add a governor counting module that allows distributing voting power amongst 3 options (For, Against, Abstain). (#5045)
• Votes: Set _moveDelegateVotes visibility to internal instead of private. (#5007)

Proxy

• Clones: Add version of clone and cloneDeterministic that support sending value at creation. (#4936)
• TransparentUpgradeableProxy: Make internal _proxyAdmin() getter have view visibility. (#4688)
• ProxyAdmin: Fixed documentation for UPGRADE_INTERFACE_VERSION getter. (#5031)

Tokens

• ERC1363: Add implementation of the token payable standard allowing execution of contract code after transfers and approvals. (#4631)
• ERC20TemporaryApproval: Add an ERC-20 extension that implements temporary approval using transient storage, based on ERC7674 (draft). (#5071)
• SafeERC20: Add "relaxed" function for interacting with ERC-1363 functions in a way that is compatible with EOAs. (#4631)
• SafeERC20: Document risks of safeIncreaseAllowance and safeDecreaseAllowance when associated with ERC-7674. (#5262)
• ERC721Utils and ERC1155Utils: Add reusable libraries with functions to perform acceptance checks on IERC721Receiver and IERC1155Receiver implementers. (#4845)
• ERC1363Utils: Add helper similar to the existing ERC721Utils and ERC1155Utils. (#5133)

Utils

• Arrays: add a sort functions for address[], bytes32[] and uint256[] memory arrays. (#4846)
• Arrays: add new functions lowerBound, upperBound, lowerBoundMemory and upperBoundMemory for lookups in sorted arrays with potential duplicates. (#4842)
• Arrays: deprecate findUpperBound in favor of the new lowerBound. (#4842)
• Base64: Add encodeURL following section 5 of RFC4648 for URL encoding (#4822)
• Comparator: A library of comparator functions, useful for customizing the behavior of the Heap structure. (#5084)
• Create2: Bubbles up returndata from a deployed contract that reverted during construction. (#5052)
• Create2, Clones: Mask computeAddress and cloneDeterministic outputs to produce a clean value for an address type (i.e. only use 20 bytes) (#4941)
• Errors: New library of common custom errors. (#4936)
• Hashes: A library with commonly used hash functions. (#3617)
• Packing: Added a new utility for packing, extracting and replacing bytesXX values. (#4992)
• Panic: Add a library for reverting with panic codes. (#3298)
• ReentrancyGuardTransient: Added a variant of ReentrancyGuard that uses transient storage. (#4988)
• Strings: Added a utility function for converting an address to checksummed string. (#5067)
• SlotDerivation: Add a library of methods for derivating common storage slots. (#4975)
• TransientSlot: Add primitives for operating on the transient storage space using a typed-slot representation. (#4980)

Cryptography

• SignatureChecker: refactor isValidSignatureNow to avoid validating ECDSA signatures if there is code deployed at the signer's address. (#4951)
• MerkleProof: Add variations of verify, processProof, multiProofVerify and processMultiProof (and equivalent calldata version) with support for custom hashing functions. (#4887)
• P256: Library for verification and public key recovery of P256 (aka secp256r1) signatures. (#4881)
• RSA: Library to verify signatures according to RFC 8017 Signature Verification Operation (#4952)

Math

• Math: add an invMod function to get the modular multiplicative inverse of a number in Z/nZ. (#4839)
• Math: Add modExp function that exposes the EIP-198 precompile. Includes uint256 and bytes memory versions. (#3298)
• Math: Custom errors replaced with native panic codes. (#3298)
• Math, SignedMath: Add a branchless ternary function that computescond ? a : b in constant gas cost. (#4976)
• SafeCast: Add toUint(bool) for operating on bool values as uint256. (#4878)

Structures

• CircularBuffer: Add a data structure that stores the last N values pushed to it. (#4913)
• DoubleEndedQueue: Custom errors replaced with native panic codes. (#4872)
• EnumerableMap: add UintToBytes32Map, AddressToAddressMap, AddressToBytes32Map and Bytes32ToAddressMap. (#4843)
• Heap: A data structure that implements a heap-based priority queue. (#5084)
• MerkleTree: A data structure that allows inserting elements into a merkle tree and updating its root hash. (#3617)

Breaking changes

• ERC1967Utils: Removed duplicate declaration of the Upgraded, AdminChanged and BeaconUpgraded events. These events are still available through the IERC1967 interface located under the contracts/interfaces/ directory. Minimum pragma version is now 0.8.21.
• Governor, GovernorCountingSimple: The _countVotes virtual function now returns an uint256 with the total votes casted. This change allows for more flexibility for partial and fractional voting. Upgrading users may get a compilation error that can be fixed by adding a return statement to the _countVotes function.

Custom error changes

This version comes with changes to the custom error identifiers. Contracts previously depending on the following errors should be replaced accordingly:

• Replace Address.FailedInnerCall with Errors.FailedCall
• Replace Address.AddressInsufficientBalance with Errors.InsufficientBalance
• Replace Clones.Create2InsufficientBalance with Errors.InsufficientBalance
• Replace Clones.ERC1167FailedCreateClone with Errors.FailedDeployment
• Replace Clones.Create2FailedDeployment with Errors.FailedDeployment
• SafeERC20: Replace Address.AddressEmptyCode with SafeERC20FailedOperation if there is no code at the token's address.
• SafeERC20: Replace generic Error(string) with SafeERC20FailedOperation if the returned data can't be decoded as bool.
• SafeERC20: Replace generic SafeERC20FailedOperation with the revert message from the contract call if it fails.

Changes by category

General

• AccessManager, VestingWallet, TimelockController and ERC2771Forwarder: Added a public initializer function in their corresponding upgradeable variants. (#5008)

Access

• AccessControlEnumerable: Add a getRoleMembers method to return all accounts that have role. (#4546)
• AccessManager: Allow the onlyAuthorized modifier to restrict functions added to the manager. (#5014)

Finance

• VestingWalletCliff: Add an extension of the VestingWallet contract with an added cliff. (#4870)

Governance

• GovernorCountingFractional: Add a governor counting module that allows distributing voting power amongst 3 options (For, Against, Abstain). (#5045)
• Votes: Set _moveDelegateVotes visibility to internal instead of private. (#5007)

Proxy

• Clones: Add version of clone and cloneDeterministic that support sending value at creation. (#4936)
• TransparentUpgradeableProxy: Make internal _proxyAdmin() getter have view visibility. (#4688)
• ProxyAdmin: Fixed documentation for UPGRADE_INTERFACE_VERSION getter. (#5031)

Tokens

• ERC1363: Add implementation of the token payable standard allowing execution of contract code after transfers and approvals. (#4631)
• ERC20TemporaryApproval: Add an ERC-20 extension that implements temporary approval using transient storage, based on ERC7674 (draft). (#5071)
• SafeERC20: Add "relaxed" function for interacting with ERC-1363 functions in a way that is compatible with EOAs. (#4631)
• ERC721Utils and ERC1155Utils: Add reusable libraries with functions to perform acceptance checks on IERC721Receiver and IERC1155Receiver implementers. (#4845)
• ERC1363Utils: Add helper similar to the existing ERC721Utils and ERC1155Utils. (#5133)

Utils

• Arrays: add a sort functions for address[], bytes32[] and uint256[] memory arrays. (#4846)
• Arrays: add new functions lowerBound, upperBound, lowerBoundMemory and upperBoundMemory for lookups in sorted arrays with potential duplicates. (#4842)
• Arrays: deprecate findUpperBound in favor of the new lowerBound. (#4842)
• Base64: Add encodeURL following section 5 of RFC4648 for URL encoding (#4822)
• Comparator: A library of comparator functions, useful for customizing the behavior of the Heap structure. (#5084)
• Create2: Bubbles up returndata from a deployed contract that reverted during construction. (#5052)
• Create2, Clones: Mask computeAddress and cloneDeterministic outputs to produce a clean value for an address type (i.e. only use 20 bytes) (#4941)
• Errors: New library of common custom errors. (#4936)
• Hashes: A library with commonly used hash functions. (#3617)
• Packing: Added a new utility for packing, extracting and replacing bytesXX values. (#4992)
• Panic: Add a library for reverting with panic codes. (#3298)
• ReentrancyGuardTransient: Added a variant of ReentrancyGuard that uses transient storage. (#4988)
• Strings: Added a utility function for converting an address to checksummed string. (#5067)
• SlotDerivation: Add a library of methods for derivating common storage slots. (#4975)
• StorageSlot: Add primitives for operating on the transient storage space using a typed-slot representation. (#4980)

Cryptography

• SignatureChecker: refactor isValidSignatureNow to avoid validating ECDSA signatures if there is code deployed at the signer's address. (#4951)
• MerkleProof: Add variations of verify, processProof, multiProofVerify and processMultiProof (and equivalent calldata version) with support for custom hashing functions. (#4887)
• P256: Library for verification and public key recovery of P256 (aka secp256r1) signatures. (#4881)
• RSA: Library to verify signatures according to RFC 8017 Signature Verification Operation (#4952)

Math

• Math: add an invMod function to get the modular multiplicative inverse of a number in Z/nZ. (#4839)
• Math: Add modExp function that exposes the EIP-198 precompile. Includes uint256 and bytes memory versions. (#3298)
• Math: Custom errors replaced with native panic codes. (#3298)
• Math, SignedMath: Add a branchless ternary function that computescond ? a : b in constant gas cost. (#4976)
• SafeCast: Add toUint(bool) for operating on bool values as uint256. (#4878)

Structures

• CircularBuffer: Add a data structure that stores the last N values pushed to it. (#4913)
• DoubleEndedQueue: Custom errors replaced with native panic codes. (#4872)
• EnumerableMap: add UintToBytes32Map, AddressToAddressMap, AddressToBytes32Map and Bytes32ToAddressMap. (#4843)
• Heap: A data structure that implements a heap-based priority queue. (#5084)
• MerkleTree: A data structure that allows inserting elements into a merkle tree and updating its root hash. (#3617)

• Base64: Fix issue where dirty memory located just after the input buffer is affecting the result. (#4926)

• ERC2771Context and Context: Introduce a _contextPrefixLength() getter, used to trim extra information appended to msg.data.
• Multicall: Make aware of non-canonical context (i.e. msg.sender is not _msgSender()), allowing compatibility with ERC2771Context.